









<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>iBaGuice - Introduction</title>
    <link rel="stylesheet" href="./css/maven-theme.css" type="text/css" />
    <link rel="stylesheet" href="./css/maven-base.css" type="text/css"/>
    <link rel="stylesheet" href="./css/prettify.css" type="text/css"/>
    <link rel="stylesheet" href="./css/print.css" type="text/css" media="print" />
    <script type="text/javascript" src="./js/prettify.js"></script>
    <script type="text/javascript" src="./js/niftycube.js"></script>
    <script type="text/javascript">
        window.onload=function() {
            Nifty("div\#wrapper", "big");
            Nifty("div#breadcrumbs", "small");
            Nifty("div\#navcolumn", "small");
            Nifty("div.source", "medium");
            prettyPrint();
        }
    </script>
          <meta name="author" content="The iBaGuice Team" />
          </head>
  <body>
    <div id="wrapper">
        <div id="banner">
                      <a href="http://ibaguice.googlecode.com/svn/site/1.0-beta-1/index.html" id="bannerLeft"  >
    
                                            <img src="images/logo.png" alt="iBaGuice: enjoy the power of iBatis + Google Guice" />
    
            </a>
                            <div class="clear">
            <hr/>
          </div>
        </div>
        <div id="breadcrumbs">
              
  

  
    
            
  
    
            <div class="xleft">
        <span id="publishDate">Last Published: 2010-02-10</span>
                  &nbsp;| <span id="projectVersion">Version: 1.0-beta-1</span>
                      </div>
                <div class="xright">      
  

  
    
            
  
    
  </div>
          <div class="clear">
            <hr/>
          </div>
        </div>
        <div id="leftColumn">
          <div id="navcolumn">
               
  

  
    
            
  
    
                       <h5>iBaGuice - Main</h5>
            <ul>
              
    <li class="none">
                    <a href="index.html">Introduction</a>
          </li>
              
    <li class="none">
              <strong>The Core components</strong>
        </li>
              
    <li class="none">
                    <a href="dao.html">The DAO Module</a>
          </li>
          </ul>
              <h5>Data Sources</h5>
            <ul>
              
    <li class="none">
                    <a href="datasource.html#Unpooled_Data_Source_Provider">Unpooled Data Source Provider</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#Pooled_Data_Source_Provider">Pooled Data Source Provider</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#JNDI_Data_Source_Provider">JNDI Data Source Provider</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#Basic_Data_Source_Provider">Basic Data Source Provider</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#Shared_Pool_Data_Source">Shared Pool Data Source</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#Per_User_Pool_DataSource">Per User Pool DataSource</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#Connection_Pool_Data_Source_driver_adapter">Connection Pool Data Source driver adapter</a>
          </li>
              
    <li class="none">
                    <a href="datasource.html#C3P0_Provider">C3P0 Provider</a>
          </li>
          </ul>
              <h5>Caching support</h5>
            <ul>
              
    <li class="none">
                    <a href="caching.html#Ehcache">Ehcache</a>
          </li>
              
    <li class="none">
                    <a href="caching.html#Hazelcast">Hazelcast</a>
          </li>
              
    <li class="none">
                    <a href="caching.html#JBoss_Cache">JBoss Cache</a>
          </li>
              
    <li class="none">
                    <a href="caching.html#Memcached">Memcached</a>
          </li>
              
    <li class="none">
                    <a href="caching.html#OSCache">OSCache</a>
          </li>
          </ul>
              <h5>Miscellaneous</h5>
            <ul>
              
    <li class="none">
                    <a href="stats.html">Project stats</a>
          </li>
              
    <li class="none">
                    <a href="iBaGuice-1.0-beta-1.pdf">PDF Manual</a>
          </li>
          </ul>
              <h5>Project Documentation</h5>
            <ul>
              
                
                    
                  
                  
                  
                  
                  
                  
                  
                  
                  
                  
                  
              
        <li class="collapsed">
                    <a href="project-info.html">Project Information</a>
                </li>
              
                
                    
                  
                  
                  
              
        <li class="collapsed">
                    <a href="project-reports.html">Project Reports</a>
                </li>
          </ul>
              <h5>Modules</h5>
            <ul>
              
    <li class="none">
                    <a href="ibaguice-core/index.html">Core</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-dao/index.html">DAO</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-c3p0/index.html">c3p0</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-dbcp/index.html">Apache DBCP</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-oscache/index.html">OSCache</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-memcached/index.html">Memcached</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-ehcache/index.html">Ehcache</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-jbosscache/index.html">JBoss Cache</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-hazelcast/index.html">Hazelcast Cache</a>
          </li>
              
    <li class="none">
                    <a href="ibaguice-samples/index.html">Samples</a>
          </li>
          </ul>
              <h5>External Links</h5>
            <ul>
              
    <li class="none">
                    <a href="">Project Page</a>
          </li>
              
    <li class="none">
                    <a href="http://ibatis.apache.org/" class="externalLink">iBatis</a>
          </li>
              
    <li class="none">
                    <a href="../google-guice/">Google Guice</a>
          </li>
          </ul>
                                               <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy">
            <img class="poweredBy"
                 alt="Built by Maven"
                 src="./images/logos/maven-feather.png"
                 width="90"
                 height="30"
                 border="1" />
          </a>
                           
  

  
    
            
  
    
            </div>
        </div>
        <div id="bodyColumn">
          <div id="contentBox">
            <div class="section"><h2>The Core components</h2>
<p>The <tt>com.google.code.ibaguice.core</tt> package prodives a set of reusable simple Guice <tt>Provider</tt> and <tt>Module</tt> that alleviate users the task to create iBatis objects</p>
<p>To use the <tt>core</tt> <i>iBaGuice</i> module add the following <tt>dependency</tt> to your <tt>pom.xml</tt>:</p>
<div class="source"><pre>&lt;dependencies&gt;
    ...
    &lt;dependency&gt;
        &lt;groupId&gt;com.google.code.ibaguice&lt;/groupId&gt;
        &lt;artifactId&gt;ibaguice-core&lt;/artifactId&gt;
        &lt;version&gt;XX.XX&lt;/version&gt;
    &lt;/dependency&gt;
    ...
&lt;/dependencies&gt;</pre>
</div>
<div class="section"><h3>Building SqlSessionFactory from XML</h3>
<p>The class <tt>XMLSqlSessionFactoryProvider</tt> builds for you the iBatis <tt>org.apache.ibatis.session.SqlSessionFactory</tt> simply by reading the configuration classpath resource. Users can use that provider in two ways:</p>
<ul><li>specifying in the <tt>com.google.inject.name.Named</tt> property called <tt>ibatis.classpathResource</tt>, then in your module the provider mapping looks like:<div class="source"><pre>binder.bindConstant()
      .annotatedWith(com.google.inject.name.Names.named(&quot;ibatis.classpathResource&quot;))
      .to(&quot;com/acme/ibatis-config.xml&quot;); // feel free to get this value with the way you prefeer
...
binder.bind(org.apache.ibatis.session.SqlSessionFactory.class)
      .toProvider(XMLSqlSessionFactoryProvider.class)
      .asEagerSingleton();</pre>
</div>
</li>
<li>or invoking directly the provider instantiation: looks like:<div class="source"><pre>binder.bind(SqlSessionFactory.class)
      .toProvider(new XMLSqlSessionFactoryProvider(&quot;com/acme/ibatis-config.xml&quot;));</pre>
</div>
</li>
</ul>
</div>
<div class="section"><h3>Building SqlSessionFactory from Java</h3>
<p>Confronting to the previous approach, this is the way we prefer to configure the <tt>org.apache.ibatis.session.SqlSessionFactory</tt> since we can play a little with iBatis settings and easily integrate 3rd part technologies we need.</p>
<p>The core component of this aproach is the <tt>com.google.code.ibaguice.core.core.SqlSessionFactoryModule</tt> that's able to create, through a serie of required and optional <tt>com.google.inject.Provider</tt>, the <tt>org.apache.ibatis.session.SqlSessionFactory</tt>.</p>
<p>The best way to start is just adding the module into the <tt>com.google.inject.Injector</tt> as shown below and explain details step by step:</p>
<div class="source"><pre>import com.google.code.ibaguice.core.SqlSessionFactoryModule;
import com.google.inject.Guice;
import com.google.inject.Injector;
import com.google.inject.Provider;
import javax.sql.DataSource;
import org.apache.ibatis.session.SqlSessionFactory;
import org.apache.ibatis.transaction.TransactionFactory;

...

Class&lt;? extends Provider&lt;DataSource&gt;&gt; dataSourceProviderClass = [...];
Class&lt;? extends Provider&lt;TransactionFactory&gt;&gt; txFactoryProviderClass = [...];

Injector injector = Guice.createInjector(
    new SqlSessionFactoryModule(dataSourceProviderClass, txFactoryProviderClass),
    ...
);

SqlSessionFactory sessionFactory = injector.getInstance(SqlSessionFactory.class);</pre>
</div>
<p>Let's have a look now at required and optional providers.</p>
<div class="section"><h4>Required properties</h4>
<p>The <tt>org.apache.ibatis.mapping.Environment</tt> needs to know the environment id, so users have to take care of setting the <tt>ibatis.environment.id</tt> property as a Guice constant, for example:</p>
<div class="source"><pre>binder.bindConstant()
    .annotatedWith(com.google.inject.name.Names.named(&quot;ibatis.environment.id&quot;))
    .to(&quot;production&quot;);</pre>
</div>
<p>Feel free to read and set it in any way you prefeer, we suggest to put it in a properties file (maybe filtered and set depending on for wich environment you're building the application), but don't forget it otherwise the injection won't work.</p>
</div>
<div class="section"><h4>Optional properties</h4>
<p>If you need to enable the <i>lazy loading</i> in the iBatis <tt>org.apache.ibatis.session.Configuration</tt>, then bind the named property <tt>ibatis.configuration.lazyLoadingEnabled</tt> with the required boolean value. By default, if <tt>ibatis.configuration.lazyLoadingEnabled</tt> is not specified, the property will be ignored and iBatis will take care about proper default <i>lazy loading</i> initialization.</p>
<div class="source"><pre>binder.bindConstant()
    .annotatedWith(com.google.inject.name.Names.named(&quot;ibatis.configuration.lazyLoadingEnabled&quot;))
    .to(true);</pre>
</div>
</div>
<div class="section"><h4>The Data Source provider</h4>
<p>This is one of two required providers that has the task to create and provide the <tt>javax.sql.DataSource</tt> managed by iBatis.</p>
<p>This library comes with some providers that support the iBatis-native Data Sources and two other well known Data Sources, <i>C3P0</i> and <i>Apache commons-dbcp</i>, but users are free to write their own <i>DataSourceProvider</i> and reference it in the <tt>com.google.code.ibaguice.core.SqlSessionFactoryModule</tt>.</p>
<p>Please read the Data Source <a href="datasource.html">reference</a> to obtain more informations about natively supported providers.</p>
</div>
<div class="section"><h4>The Transaction Factory Provider</h4>
<p>This provider has to serve the iBatis Transaction Manager Factory; the library comes with the native iBatis implementation providers: <tt>com.google.code.ibaguice.core.transactionfactory.JdbcTransactionFactoryProvider</tt> that provides the iBatis JDBC Transaction Manager Factory, and the <tt>com.google.code.ibaguice.core.transactionfactory.ManagedTransactionFactoryProvider</tt>, that provides the iBatis user managed Transaction Manager Factory.</p>
<p>Users are free to write their own <i>TransactionFactoryProvider</i> and reference it in the <tt>com.google.code.ibaguice.core.SqlSessionFactoryModule</tt>.</p>
</div>
<div class="section"><h4>Configuring aliases</h4>
<p>Once users create the <tt>com.google.code.ibaguice.core.SqlSessionFactoryModule</tt>, it's quite easy plugging optional iBatis components, like aliases: here users can define simple aliases, for example <tt>Foo</tt> that stands for <tt>com.acme.Foo</tt>, or custom aliases, for example <tt>MyFoo</tt> that stands for <tt>com.acme.Foo</tt>.</p>
<p>We found very useful adding simple aliases because helped us a lot to reduce the errors during our development time; just call:</p>
<div class="source"><pre>com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.addSimpleAliases(com.acme.Foo.class, com.acme.Bar.class, ...);</pre>
</div>
<p>If you prefeer instead using you own custom aliases, just invoke</p>
<div class="source"><pre>com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.addAlias(&quot;MyFoo&quot;, com.acme.Foo.class)
module.addAlias(&quot;MyBar&quot;, com.acme.Bar.class);
...</pre>
</div>
</div>
<div class="section"><h4>Configuring Type Handlers</h4>
<p>Like users can configure aliases, the can do it the same for type aliases: given my <tt>com.acme.Foo</tt> type, that has to be hanlded by the type handler <tt>com.acme.dao.FooHandler</tt>, just invoke</p>
<div class="source"><pre>com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.addTypeHandler(com.acme.Foo.class, com.acme.dao.FooHandler.class);
module.addTypeHandler(com.acme.Bar.class, com.acme.dao.BarHandler.class);
...</pre>
</div>
<p>and let google-guice creating the handler and bind it to iBatis.</p>
</div>
<div class="section"><h4>Configuring Interceptor Plugins</h4>
<p>Users can easily add their preferred <tt>org.apache.ibatis.plugin.Interceptor</tt> simply invoking:</p>
<div class="source"><pre>com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.setInterceptorsClasses(com.acme.dao.FooInterceptor.class, com.acme.dao.BarInterceptor.class, ...);</pre>
</div>
</div>
<div class="section"><h4>Configuring Mappers</h4>
<p>Users can add the mapper classes adding them to the module, iBaGuice will take care to inject them accurately:</p>
<div class="source"><pre>com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.setMapperClasses(com.acme.dao.FooMapper.class, com.acme.dao.BarMapper.class, ...);</pre>
</div>
</div>
<div class="section"><h4>Configuring the Object Factory</h4>
<p>Just simply define the <tt>com.google.inject.Provider</tt> for your own <tt>org.apache.ibatis.reflection.factory.ObjectFactory</tt> and communicate it to the module and let google-guice create it:</p>
<div class="source"><pre>com.google.code.ibaguice.core.SqlSessionFactoryModule module = [...]
module.setObjectFactoryProviderClass(com.acme.MyObjectFactoryProvider.class);</pre>
</div>
</div>
</div>
</div>

          </div>
        </div>
        <div class="clear">
          <hr/>
        </div>
        <div id="footer">
          <div class="xright">Copyright &#169;         
   
          2010.
    
      All Rights Reserved.    
  

  
    
            
  
    
  </div>
          <div class="clear">
            <hr/>
          </div>
        </div>
    </div>
  </body>
</html>
